home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48hor1 / mldl.doc < prev    next >
Text File  |  1995-03-31  |  15KB  |  386 lines
  1. (Comp.sys.handhelds) Option: 
  2. Item: 2563 by bson at erice.ai.mit.edu 
  3. Author: [Jan Brittenson] 
  4.   Subj: HP-48 MLDL beta 1.01 (Instructions) 
  5.   Date: Sat Mar 30 1991 
  6.  
  7. [Note: Jan has updated this library.  Contact him for details.  -jkh-] 
  8.  
  9.   This is the beta release of the HP-48 Machine Language Development Library. 
  10. It is intended for test and review purposes only.  No source code is available. 
  11.  
  12.   I'm working on breakpoints - patience, it is not trivial to get it right! 
  13.  
  14.   The post is divided into two parts: this, the first part, contains the user's 
  15. guide.  The second part, posted separately, contains the code both uuencoded 
  16. and in Wickes' ASC format.  The library is roughly 7kbytes, and so you need 
  17. 28kbytes of free memory to load the ASC version. 
  18.  
  19.   The MLDL can not be run from ROM since it's self-modifying (but it updates 
  20. the CRC to keep the system from complaining). 
  21.  
  22.                                                 -- Jan Brittenson 
  23.                                                    bson@ai.mit.edu 
  24.  
  25.  O  / 
  26.   \/ 
  27.   /\  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
  28.  O  \ 
  29.  
  30.  
  31. MLDL 1.01, MARCH 1991 
  32. --------------------- 
  33.  
  34.  
  35.   This is a Machine Language Development Library for the HP-48SX.  The library 
  36. currently consists of 4 named commands, and has been given the number 1092 
  37. decimal (hex 444).  To install it, load the binary file to your calculator and 
  38. store it in a suitable port.  Turn the calculator off, then back on, and go to 
  39. the directory where you wish to attach it.  Enter :p:1092 where `p' is the port 
  40. you stored it in, then ATTACH.  To remove it, go to the directory where you 
  41. previously attached it, enter `:p:1092', press DUP DETACH, then PURGE.  The 
  42. library does not automatically attach. 
  43.  
  44. Installation example, assuming I/O has been properly set up: 
  45.  
  46.         HOME 
  47.         'MLDL' KGET 
  48.         MLDL :0:1092 STO 
  49.  
  50.         (Turn the calculator OFF, then back ON) 
  51.  
  52.         :0:1092 ATTACH 
  53.  
  54.  
  55. Removal example: 
  56.  
  57.         HOME 
  58.         :0:1092 ENTER DUP 
  59.         DETACH 
  60.         PURGE 
  61.  
  62.   The display should briefly flicker as you purge the library from the port. 
  63.  
  64.  
  65.  
  66. LIBRARY COMMANDS 
  67. ---------------- 
  68.  
  69.  
  70. [Version] 
  71.  
  72.   Returns to level 2 a version string, and to level 1 a copyright string.  They 
  73. will resemble the output below. 
  74.  
  75.  
  76.         2: "Saturn MLDL 1.01, March 1991" 
  77.         1: "Copyright Jan Brittenson" 
  78.  
  79.  
  80.  
  81. [MLDB] 
  82.  
  83.   Saturn ML Debugger.  Lets you single-step ML programs, examine registers and 
  84. memory contents.  Since it single-steps ML it is not useful for debugging RPL 
  85. code - unless you wish to follow your RPL thread on an ML level.  MLDB expects 
  86. an argument in level 1: 
  87.  
  88.  
  89.         Code object 
  90.  
  91.                 Halts before the first instruction of the code object. 
  92.             Both the PC and A registers are set to the address of the 
  93.             first instruction. 
  94.  
  95.         XLIB 
  96.  
  97.             The XLIB is must be a code object, which is debugged. 
  98.  
  99.         Binary integer 
  100.  
  101.                 Treats the binary integer as the address of a prefixed 
  102.             machine code routine (PMC). Halts at the first instruction 
  103.             of the PMC. PMCs consist of a 5-nybble pointer to the first 
  104.             instruction which is usually, but not always, the address 
  105.             of the PMC plus 5. 
  106.  
  107.         @#3a81 (True) 
  108.  
  109.         Any object other than @#3a81 
  110.  
  111.                 Ignored - the debugger returns immediately. In the 
  112.             future, @#3a81 (True) will cause the debugger to use the 
  113.             next object in sequence. It will be possible to include a 
  114.             call to MLDB and precede it with a test to determine 
  115.             whether to actually debug or run free. A user flag test, 
  116.             for instance. 
  117.  
  118.  
  119.   The debugger uses the PICT for display, but in the future probably will have 
  120. its own display GROB.  Since all information will not fit on the display at 
  121. once, it has been divided into 6 screens.  Only one screen is active at any one 
  122. time.  Switching between screens is done by means of the 6 menu keys, here 
  123. refered to as A-F, which correspond to screen 1 through 6 respectively. 
  124.  
  125.   The sample screens below are from the first instruction of the PMC at #59CC, 
  126. and can be reproduced by: 
  127.  
  128.         #59CC MLDB 
  129.  
  130.  
  131.  
  132. Screen 1  - CPU State (key [A]) 
  133.  
  134.         |CALL.4 #0679B         |   - Mnemonic 
  135.         | 8E4CD0               |   - Opcode 
  136.         |@:059D1 P:0 CH ST:218 |   - PC, P, Carry, Hex/Dec mode, ST 
  137.         |A:000CC C:77794       |   - A.A and C.A 
  138.         |B:729A9 D:00F96 HST:2 |   - B.A, D.A, and HST 
  139.         |D0:409C1/9540A8240BC9 |   - D0 and 6 bytes @D0 
  140.         |D1:77799/000000000000 |   - D1 and 6 bytes @D1 
  141.         | 8E4CD0               |   - Opcode 
  142.         |@:059D1 P:0 CH ST:218 |   - PC, P, Carry, Hex/Dec mode, ST 
  143.         |A:00000005444000CC    |   - Register A 
  144.         |B:000000000007611E    |   - Register B 
  145.         |C:000000000007792C    |   - Register C 
  146.         |D:00000000000004D0    |   - Register D 
  147.         |RST:00000:00000:00000 |   - Top 3 levels of RSTK 
  148.  
  149.  
  150. Screen 3  - Data registers (key [C]) 
  151.  
  152.         |CALL.4 #0679B         |   - Mnemonic 
  153.         | 8E4CD0               |   - Opcode 
  154.         |@:059D1 P:0 CH ST:218 |   - PC, P, Carry, Hex/Dec mode, ST 
  155.         |R0:053385D439800040   |   - Register R0 
  156.         |R1:00000005444059D1   |   - Register R1 
  157.         |R2:0000000000075BC1   |   - Register R2 
  158.         |R3:0000000544402E92   |   - Register R3 
  159.         |R4:00015075A6375AA1   |   - Register R4 
  160.         |RST:00000:00000:00000 |   - Top 3 levels of RSTK 
  161.  
  162.  
  163. Screen 4  - Return stack (key [D]) 
  164.  
  165.         |CALL.4 #0679B         |   - Mnemonic 
  166.         | 8E4CD0               |   - Opcode 
  167.         |@:059D1 P:0 CH ST:218 |   - PC, P, Carry, Hex/Dec mode, ST 
  168.         |                      | 
  169.         |RST0:00000 RST4:00000 |   - RSTK levels 0 and 4 
  170.         |RST1:00000 RST5:00000 |   - RSTK levels 1 and 5 
  171.         |RST2:00000 RST6:00000 |   - RSTK levels 2 and 6 
  172.         |RST3:00000 RST7:00000 |   - RSTK levels 3 and 7 
  173.  
  174.  
  175. Screen 5  - Memory dump (key [E]) 
  176.  
  177.         |059A0:56113680913420CC|   - Locations 59A0-59AF 
  178.         |059B0:4E0156716FCC56FD|   - Locations 59B0-59BF 
  179.         |059C0:015B38D5E0101D95|   - Locations 59C0-59CF 
  180.         |059D0:08E4CD08E46C0101|   - Locations 59D0-59DF 
  181.         |059E0:D230574911191443|   - Locations 59E0-59EF 
  182.         |059F0:4E4A201101311456|   - Locations 59F0-59FF 
  183.         |05A00:12280A50143174E7|   - Locations 5A00-5A0F 
  184.         |05A10:8E58D01311741431|   - Locations 5A10-5A1F 
  185.  
  186.  
  187. Screen 6  - ML Instruction Stream (key [F]) 
  188.  
  189.         |@:059D1 P:0 CH ST:218 |   - PC, P, Carry, Hex/Dec mode, ST 
  190.         | CALL.4 #0679B        |   - Next 7 instructions 
  191.         | CALL.4 #06641        | 
  192.         | MOVE.W A,R1          | 
  193.         | CLR.A C             | 
  194.         | MOVE.P1 #5,C         | 
  195.         | CALL.3 #05B7D        | 
  196.         | MOVE.W R1,C          | 
  197.  
  198.  
  199. The MLDB keyboard 
  200. ----------------- 
  201.  
  202. Moving around is done with the arrow keys and the NXT key: 
  203.  
  204.         up      Decrement PC by 16 
  205.         down    Increment PC by 16 
  206.         left    Decrement PC by 1 
  207.         right   Increment PC by 1 
  208.         NXT     Move to next instruction 
  209.  
  210. In addition, there are two mark keys: 
  211.  
  212.         x       (Mulitplication key) 
  213.                 Sets the mark to the current PC. 
  214.  
  215.         +/-     Swaps the PC and the mark. 
  216.  
  217.  
  218.   Currently, there is no numerical entry and registers can't be altered.  Have 
  219. patience, this is an early version. 
  220.  
  221.   The arrow keys are most useful for moving around in the memory dump, but can 
  222. also be used to arbitrarily increment and decrement the PC to shift the 
  223. instruction stream by single nybbles. 
  224.  
  225. There are three ways of leaving the debugger: 
  226.  
  227.         delete  (Delete key) 
  228.                 Exits as is. 
  229.  
  230.         DEL     Restores system registers to their state when the 
  231.                 debugger was entered. Useful if you like to exit 
  232.                 in the middle of a program and the system registers 
  233.                 contain random values. 
  234.  
  235.         ON-C    (ON and C keys held down simultenously) 
  236.                 Panic exit. If you know the machine will crash when 
  237.                 you exit, such as if the memory has been reconfigured. 
  238.                 It may also be worth considering ON-A-E if you have 
  239.                 seriously altered the memory - say if you have stepped 
  240.                 the garbage collect half-through. 
  241.  
  242.  
  243. To step the program, use: 
  244.  
  245.         +       Single-steps one instruction, pointed to by the PC. 
  246.                 Follows CALLs. 
  247.  
  248.         -       Same as +, but does not follows CALLs; instead, the 
  249.                 program halts when it returns from the CALL. 
  250.  
  251.         .       Redraws the display but otherwise does nothing. 
  252.  
  253.  
  254.  
  255. Some system considerations 
  256. -------------------------- 
  257.  
  258.   The debugger has been designed explicitly so it will not alter any static 
  259. system data or depend on the precise machine configuration.  The only system 
  260. data it modifies is the keyboard buffer, since it relies on the system to 
  261. respond to the keyboard interrupt and manage the buffer.  Testing has shown 
  262. that interfering with this is results in poor reliability.  Still, there are 
  263. two instructions the debugger will refuse to single-step: 
  264.  
  265.         RESET 
  266.                 The effect of this would be the same as ON-C. 
  267.  
  268.         CLRB #F,ST 
  269.                 Executing this instruction would lock up your calculator 
  270.                 since it would disable all I/O most notably the keyboard. 
  271.  
  272.  
  273.   In all other aspects is the debugger self-contained, apart from a system RPL 
  274. interface to do argument type checking. 
  275.  
  276.  
  277.  
  278. A word of caution 
  279. ----------------- 
  280.  
  281.   The [-] key lets you complete an entire CALL.  But beware: the return stack 
  282. is replaced by one that will cause the called routine to return to the 
  283. debugger.  Therefore the routine called cannot rely on specific return stack 
  284. contents - or remove return addresses from the stack - which will invariably 
  285. result in a system crash.  Fortunately, this seems not to be practised in the 
  286. HP-48 ROM. 
  287.  
  288.   Despite the efforts put into avoiding system collisions, the HP-48 will still 
  289. remain a largely unprotected system where the debugger - or other parts of the 
  290. MLDL - can still be overwritten, which may result in memory loss.  Since it is 
  291. stored as a library in a port, it is not susceptible to general memory 
  292. allocation, such as dynamic memory allocation or system display GROB 
  293. allocations.  But, storing another library in the same port may cause it to 
  294. move - extreme caution is therefore advisable when single-stepping PMC that 
  295. alters stored port data.  If you are stepping a port store block copy by means 
  296. of either [+] or [-], then the MLDL may be overwritten.  If you're using [-] to 
  297. call a block copy routine within a similar context, then the library may have 
  298. moved and the subsequent return will cause a system crash and possibly memory 
  299. corruption. 
  300.  
  301.   Single-stepping a machine code program is in no way less dangerous than 
  302. allowing it to run uncontrolled.  It merely gives you some control over what 
  303. happens between instructions. 
  304.  
  305.  
  306.  
  307. [MLPR] 
  308.  
  309.   Disassembles and prints ML programs.  Accepts the same arguments as MLDB, 
  310. except @#3a81 and #3ac0 which are not recognized.  The program is printed to 
  311. the current print device - IR or Serial.  In case of problems, first check your 
  312. PRTPAR - see pages 602-611 in your Owner's Manual Volume II.  Page 611 
  313. explicitly describes the PRTPAR.  Each line consists of a mnemonic preceded by 
  314. the address.  No opcode is included, since it normally is of low interest.  Use 
  315. ML1 (described below) to build your own custom disassembler. 
  316.  
  317.  
  318.  
  319. [ML1] 
  320.  
  321.   Disassembles one ML instruction; allows you to build your own disassemblers 
  322. with special-purpose user interfaces.  It takes a binary integer in level one, 
  323. and returns two values; in level two the mnemonic form preceded by the address, 
  324. and in level one the address of the next instruction.  Thus, it is a simple 
  325. task to repeatedly call ML1.  Subtracting the addresses will yield the opcode 
  326. size, and a PEEK program can be utilized to retrieve it.  Or the instructions 
  327. can be displayed on the screen from a browser.  It is also trivial to extract 
  328. the mnemonic from the string, since the string will always be of the form: 
  329.  
  330.         "xxxxx: m" 
  331.  
  332.   where xxxxx is a 5-digit address followed by a colon and a blank.  The last 
  333. part of the string, m, is the mnemonic. 
  334.  
  335.  
  336.  
  337. COMMAND SUMMARY 
  338. --------------- 
  339.  
  340.  
  341. |-----------------------------------------------------------------------| 
  342. |                                                                       | 
  343. | Version       Returns version and copyright strings                   | 
  344. |                                                                       | 
  345. |                               --> "version" "copyright"               | 
  346. |                                                                       | 
  347. |-----------------------------------------------------------------------| 
  348. |                                                                       | 
  349. | MLDB          Saturn Machine Language Debugger                        | 
  350. |                                                                       | 
  351. |                       obj     --> any1 ... anyN                       | 
  352. |                                                                       | 
  353. |-----------------------------------------------------------------------| 
  354. |                                                                       | 
  355. | MLPR          Print Machine Language Program                          | 
  356. |                                                                       | 
  357. |                       obj     --> obj                                 | 
  358. |                                                                       | 
  359. |-----------------------------------------------------------------------| 
  360. |                                                                       | 
  361. | ML1           Single-Instruction Machine Language Disassembler        | 
  362. |                                                                       | 
  363. |                     #address  --> "instruction" #next                 | 
  364. |                                                                       | 
  365. |-----------------------------------------------------------------------+ 
  366.  
  367.  
  368.  
  369.  
  370. XLIB TABLE 
  371. ---------- 
  372.  
  373. Subject to change at random and without notice. 
  374. The library number is 444 hexadecimal, 1092 decimal. 
  375.  
  376.  
  377.         Command         Number 
  378.         ---------------------- 
  379.         Version         1092 0 
  380.         MLDB            1092 1 
  381.         MLPR            1092 2 
  382.         ML1             1092 3 
  383.  
  384.                                                 -- Jan Brittenson 
  385.                                                    bson@ai.mit.edu 
  386.